Adding Multiple References (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 6 - Picture Shapes / Using Picture Shapes

Adding Multiple References
Multiple items in a single picture can reference the same shape. You can use any of the functions that add items to a picture (GXNewPicture, GXSetPicture, GXSetPictureParts) to add multiple references to a single shape. The example in Listing 6-11 adds four new items to the house picture defined in Listing 6-1 on page 6-28. Each of these items references the same shape--a small, white rectangle. Because four items reference the same rectangle, four instances of this rectangle appear in the picture. Without overriding transforms, however, all four instances of this rectangle would appear in the same location. Therefore, the sample code in Listing 6-11 creates overriding transforms for three of the four new items.
Listing 6-11 Adding four items that reference the same shape to a house picture
gxRectangle windowGeometry = {ff(155), ff(93),
                              ff(160), ff(112)};
                          
gxShape windowRectangle;
   
gxShape insertedShapes[4];
gxTransform overridingTransforms[4];
   
windowRectangle = GXNewRectangle(&windowGeometry);
SetShapeCommonColor(windowRectangle, gxWhite);
   
insertedShapes[0] = windowRectangle;
insertedShapes[1] = windowRectangle;
insertedShapes[2] = windowRectangle;
insertedShapes[3] = windowRectangle;
   
overridingTransforms[0] = nil;
overridingTransforms[1] = GXNewTransform();
overridingTransforms[2] = GXNewTransform();
overridingTransforms[3] = GXNewTransform();

GXMoveTransform(overridingTransforms[1], ff(7), 0);
GXMoveTransform(overridingTransforms[2], ff(14), 0);
GXMoveTransform(overridingTransforms[3], ff(21), 0);
   
GXSetPictureParts(housePicture, 
                  3,  /* where to insert */
                  0,  /* how many to replace */
                  4,  /* how many to insert */
                  insertedShapes, 
                  nil, nil, 
                  overridingTransforms);
This sample code creates one rectangle shape and three transform objects. Once you insert these objects in the picture, you can dispose of them to lower their owner count to 1, as shown in Listing 6-12. Since these objects are referenced twice (once by your application and once by the house picture), disposing of them lowers their owner counts to 1, but does not free the memory associated with them. When you dispose of the house picture, QuickDraw GX disposes of these objects again and frees their memory.
Listing 6-12 Disposing of the white rectangle and the three transform objects before drawing
int count;
.
.
.
for (count = 1; count <= 3 ; count++)
   GXDisposeTransform(overridingTransforms[count]);
       
GXDisposeShape(windowRectangle);
      
GXDrawShape(housePicture);
The resulting picture is shown in Figure 6-25.
Figure 6-25 A house with four windows

Notice that the sample code in Listing 6-11 creates three separate transform objects because three different transformations are happening to the instances of the window rectangle--the second instance is moved 7 grid points to the right, the third instance is moved 14 grid points to the right, and the fourth instance is moved 21 grid points to the right.
You can specify that QuickDraw GX copy the overriding transforms when adding them to the picture (rather than adding them by reference) by setting the unique items shape attribute, as discussed in the next section.
For more information about adding multiple items referencing the same shape, see "Multiple References" beginning on page 6-10.